//  IController.hpp
//  PureMVC_C++
//
//  PureMVC Port to C++ by Tang Khai Phuong <phuong.tang@puremvc.org>
//  PureMVC - Copyright(c) 2006-2011 Futurescale, Inc., Some rights reserved.
//  Your reuse is governed by the Creative Commons Attribution 3.0 License
//
//  中文注释：
//  IController接口定义了PureMVC框架中的控制器组件的行为。
//  控制器负责管理命令与通知之间的映射关系，并在收到通知时执行相应的命令。
//  它是PureMVC框架中实现'命令与控制器'模式的核心接口。
//

#if !defined(__PUREMVC_INTERFACES_ICONTROLLER_HPP__)
#define __PUREMVC_INTERFACES_ICONTROLLER_HPP__

// STL include
#include <string>
// PureMVC include
#if !defined(__PUREMVC_HPP__)
#define __PUREMVC_INCLUDE__
#include "../PureMVC.hpp"
#endif /* __PUREMVC_HPP__ */

#include "INotification.hpp"
#include "ICommand.hpp"
#include "IAggregate.hpp"

namespace PureMVC
{
    namespace Interfaces
    {
        /**
         * PureMVC控制器的接口定义
         * The interface definition for a PureMVC Controller.
         *
         * <P>
         * 在PureMVC中，<code>IController</code>的实现者遵循'命令与控制器'策略，
         * 并承担以下责任：
         * In PureMVC, an <code>IController</code> implementor
         * follows the 'Command and Controller' strategy, and
         * assumes these responsibilities:
         * <UL>
         * <LI> 记住哪些<code>ICommand</code>用于处理哪些<code>INotifications</code>。
         * Remembering which <code>ICommand</code>s
         * are intended to handle which <code>INotifications</code>.</LI>
         * <LI> 为每个它有<code>ICommand</code>映射的<code>INotification</code>，
         * 将自己注册为<code>View</code>的<code>IObserver</code>。
         * Registering itself as an <code>IObserver</code> with
         * the <code>View</code> for each <code>INotification</code>
         * that it has an <code>ICommand</code> mapping for.</LI>
         * <LI> 当被<code>View</code>通知时，创建适当的<code>ICommand</code>实例来处理给定的<code>INotification</code>。
         * Creating a new instance of the proper <code>ICommand</code>
         * to handle a given <code>INotification</code> when notified by the <code>View</code>.</LI>
         * <LI> 调用<code>ICommand</code>的<code>execute</code>方法，传入<code>INotification</code>。
         * Calling the <code>ICommand</code>'s <code>execute</code>
         * method, passing in the <code>INotification</code>.</LI>
         * </UL>
         *
         * @see Interfaces/INotification.hpp PureMVC::Interfaces::INotification
         * @see Interfaces/INotification.hpp PureMVC::Interfaces::ICommand
         * @see Interfaces/IIterator.hpp PureMVC::Interfaces::IIterator
         * @see Interfaces/IAggregate.hpp PureMVC::Interfaces::IAggregate
         */
        struct PUREMVC_API IController
        {
#if defined(PUREMVC_USES_TR1)
            typedef std::unique_ptr<IAggregate<std::string> > NotificationNames;
#else
            typedef std::auto_ptr<IAggregate<std::string> > NotificationNames;
#endif

            /**
             * 注册一个特定的<code>ICommand</code>类作为特定<code>INotification</code>的处理器
             * Register a particular <code>ICommand</code> class as the handler
             * for a particular <code>INotification</code>.
             *
             * @param notification_name <code>INotification</code>的名称
             * @param notification_name the name of the <code>INotification</code>
             * @param command <code>ICommand</code>的命令实例
             * @param command the command of the <code>ICommand</code>
             */
            virtual void registerCommand(std::string const& notification_name, ICommand* command) = 0;

            /**
             * 执行先前注册为具有给定通知名称的<code>INotification</code>处理器的<code>ICommand</code>
             * Execute the <code>ICommand</code> previously registered as the
             * handler for <code>INotification</code>s with the given notification name.
             *
             * @param notification 要为其执行关联<code>ICommand</code>的<code>INotification</code>
             * @param notification the <code>INotification</code> to execute the associated <code>ICommand</code> for
             */
            virtual void executeCommand(INotification const& notification) = 0;

            /**
             * 从控制器检索<code>ICommand</code>实例（常量版本）
             * Retrieve an <code>ICommand</code> instance from the Controller.
             *
             * @param notification_name <code>INotification</code>的名称
             * @param notification_name the name of the <code>INotification</code>
             * @return 先前用给定<code>notification</code>注册的<code>ICommand</code>实例
             * @return the <code>ICommand</code> instance previously registered with the given <code>notification</code>.
             */
            virtual ICommand const& retrieveCommand(std::string const& notification_name) const = 0;

            /**
             * 从控制器检索<code>ICommand</code>实例（非常量版本）
             * Retrieve an <code>ICommand</code> instance from the Controller.
             *
             * @param notification_name <code>INotification</code>的名称
             * @param notification_name the name of the <code>INotification</code>
             * @return 先前用给定<code>notification</code>注册的<code>ICommand</code>实例
             * @return the <code>ICommand</code> instance previously registered with the given <code>notification</code>.
             */
            virtual ICommand& retrieveCommand(std::string const& notification_name) = 0;

            /**
             * 移除先前注册的<code>ICommand</code>到<code>INotification</code>的映射
             * Remove a previously registered <code>ICommand</code> to <code>INotification</code> mapping.
             *
             * @param notification_name 要移除<code>ICommand</code>映射的<code>INotification</code>名称
             * @param notification_name the name of the <code>INotification</code> to remove the <code>ICommand</code> mapping for
             * @return 从<code>Controller</code>中移除的<code>ICommand</code>
             * @return the <code>ICommand</code> that was removed from the <code>Controller</code>
             */
            virtual ICommand* removeCommand(std::string const& notification_name) = 0;

            /**
             * 检查是否为给定通知注册了命令
             * Check if a Command is registered for a given Notification
             *
             * @param notification_name 通知名称
             * @param notification_name
             * @return 当前是否为给定的<code>notification_name</code>注册了命令
             * @return whether a Command is currently registered for the given <code>notification_name</code>.
             */
            virtual bool hasCommand(std::string const& notification_name) const = 0;

            /**
             * 列出所有通知名称
             * List all notification name
             *
             * @return <code>notification_name</code>的聚合容器
             * @return the aggregate container of <code>notification_name</code>.
             */
            virtual NotificationNames listNotificationNames(void) const = 0;

            /**
             * 虚析构函数
             * Virtual destructor.
             */
            virtual ~IController(void);
        };
    }
}

#endif /* __PUREMVC_INTERFACES_ICONTROLLER_HPP__ */
